<!doctype html>
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>字符集问题 - FreeMarker 手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker 手册">
<meta property="og:title" content="字符集问题">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://freemarker.org/docs/pgui_misc_charset.html">
<link rel="canoical" href="http://freemarker.org/docs/pgui_misc_charset.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css">
</head>
<body itemscope itemtype="https://schema.org/Code">
    <meta itemprop="url" content="http://freemarker.org/docs/">
    <meta itemprop="name" content="FreeMarker 手册">

  <!--[if lte IE 9]>
  <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
  <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner">            <img itemprop="image" src="logo.png" alt="FreeMarker">
</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="http://freemarker.org/docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://sourceforge.net/p/freemarker/bugs/new/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="toc.html" class="navigation-header">Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="toc.html"><span itemprop="name">FreeMarker 手册</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui.html"><span itemprop="name">程序开发指南</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_misc.html"><span itemprop="name">其它</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_misc_charset.html"><span itemprop="name">字符集问题</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div>    <div class="main-content site-width">
      <div class="content-wrapper">
  <div id="table-of-contents-wrapper" class="col-left">
      <script>var breadcrumb = ["FreeMarker 手册","程序开发指南","其它","字符集问题"];</script>
      <script src="toc.js"></script>
      <script src="docgen-resources/main.min.js"></script>
  </div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="pgui_misc_var.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_multithreading.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="pgui_misc_charset" itemprop="headline">字符集问题</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#autoid_45" data-menu-target="autoid_45">输入的字符集</a></li><li><a class="page-menu-link" href="#autoid_46" data-menu-target="autoid_46">输出的字符集</a></li></ul> </div><p>像其它大多数的Java应用程序一样，FreeMarker使用 &quot;<a href="gloss.html#gloss.unicode">UNICODE</a> 文本&quot;(UTF-16)来工作。
		不过，也有必须处理 <a href="gloss.html#gloss.charset">字符集</a> 的情况，
		因为它不得不和外界交换数据，这就会使用到很多字符集。</p>
          



<h2 class="content-header header-section2" id="autoid_45">输入的字符集</h2>


          <p>当 FreeMarker 要加载模板文件(或没有解析的文本文件)时，
		  那就必须要知道文件使用的字符集，因为文件的存储是原生的字节序列。
		  可以使用 <code class="inline-code">encoding</code> <a href="pgui_config_settings.html">配置</a> 来确定字符集。
		  这个配置项只在 FreeMarker 使用 <code class="inline-code">Configuration</code> 
		  对象的 <code class="inline-code">getTemplate</code> 
		  方法加载模板(解析过的或没有解析过的)时起作用。请注意 <a href="ref_directive_include.html#ref.directive.include"><code>include</code> 指令 </a> 
		  在内部也使用了这个方法，所以 <code class="inline-code">encoding</code> 
		  的值对一个已经加载的模板，而且如果这个模板包含 <code class="inline-code">include</code> 
		  指令的调用来说很重要。</p>

          <p><code class="inline-code">encoding</code> 配置的getter和setter方法在第一个(配置)层面很特殊。
		  getter方法猜想返回值是基于 <code class="inline-code">Locale</code>(本地化，译者注)传递的参数；
		  它在地图区域编码表(称为编码地图)中查询编码，如果没有找到该区域，就返回默认编码。
		  可以使用配置对象的 <code class="inline-code">setEncoding(Locale locale, String encoding)</code> 
		  方法来填充编码表；编码表初始化时是空的。默认的初始编码是系统属性 
		  <code class="inline-code">file.encoding</code> 的值，但是可以通过 
		  <code class="inline-code">setDefaultEncoding</code> 方法来设置一个不同的默认值，而不是依赖它。
		  对于新项目来说，默认的编码设置就是 <code class="inline-code">utf-8</code>。</p>

          <p>也可以在模板层或运行环境层(当指定编码值作为 <code class="inline-code">getTemplate</code> 
		  方法的参数时，应该在模板层覆盖 <code class="inline-code">encoding</code> 设置)直接给定值来覆盖 
		  <code class="inline-code">encoding</code> 的设置。如果不覆盖它，那么 <code class="inline-code">locale</code> 
		  设置的有效值将会是 <code class="inline-code">configuration.getEncoding(Locale)</code> 方法的返回值。</p>

          <p>而且，代替这种基于字符集猜测的机制，也可以在模板文件中使用
		  <a href="ref_directive_ftl.html#ref.directive.ftl"><a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code></a>
          指令</a>, 比如 <code class="inline-code">&lt;#ftl
          encoding=&quot;utf-8&quot;&gt;</code> 来指定特定的字符集。</p>

          <p>请注意，模板使用的字符集和模板生成的输出内容的字符集是独立的
		  (除非包含 FreeMarker 的软件故意将设置输出内容的字符集和模板字符集设置成相同的)。</p>
        
          



<h2 class="content-header header-section2" id="autoid_46">输出的字符集</h2>


            <div class="callout note">
    <strong class="callout-label">Note:</strong>

            <p><code class="inline-code">output_encoding</code> 设置/参数和 <a href="ref_builtins_string.html#ref_builtin_url">内建函数<code>url</code></a> 
			从FreeMarker 2.3.1版本开始才可以使用，而在2.3以前的版本中是不存在的。</p>
            </div>


          <p>原则上，FreeMarker 不处理输出内容的字符集问题，
			因为 FreeMarker 将输出内容都写入了 <code class="inline-code">java.io.Writer</code> 
			对象中。而 <code class="inline-code">Writer</code> 
			对象是由封装了 FreeMarker(比如Web应用框架) 的软件生成的，
			那么输出内容的字符集就是由封装软件来控制的。而FreeMarker有一个称为
			<code class="inline-code">output_encoding</code>(开始于 FreeMarker 2.3.1 版本之后)的设置。
			封装软件应该使用这个设置(<code class="inline-code">Writer</code>对象使用的字符集)
			来通知 FreeMarker 在输出中(否则 FreeMarker 不能找到它)使用哪种字符集。
			有一些新的特性，如<a href="ref_builtins_string.html#ref_builtin_url">内建函数<code>url</code></a>，<a href="ref_specvar.html">特殊变量<code>output_encoding</code></a> 
			也利用这个信息。因此，如果封装软件没有设置字符集这个信息，
			那么 FreeMarker 需要知道输出字符集的特性就不能被利用了。</p>

          <p>如果你使用 FreeMarker 来编写软件，
		  你也许想知道在输出内容中到底选择了哪种字符集。
		  当然这取决于运行 FreeMarker 输出内容的计算机本身，
		  但是如果用户对这个问题可以变通，
		  那么通用的实践是使用模板文件的字符集作为输出的字符集，或者使用UTF-8。
		  通常使用UTF-8是最佳的实践，因为任意的文本可能来自数据模型，
		  那就可能包含不能被模板字符集所编码的字符。</p>

          <p>如果使用了 
		  <code class="inline-code">Template.createProcessingEnvironment(<em class="code-color">...</em>)</code> 
		  和 <code class="inline-code">Environment.process(<em class="code-color">...</em>)</code> 方法来代替 
		  <code class="inline-code">Template.process(<em class="code-color">...</em>)</code> 方法，
		  FreeMarker 的设置可以对任意独立执行的模板进行。
		  因此，你可以对每个独立执行的模板设置 <code class="inline-code">output_encoding</code> 信息：</p>

          

<div class="code-wrapper"><pre class="code-block code-unspecified">Writer w = new OutputStreamWriter(out, outputCharset);
Environment env = template.createProcessingEnvironment(dataModel, w);
env.setOutputEncoding(outputCharset);
env.process();</pre></div>
        <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_var.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_multithreading.html"><span>Next</span></a></div></div></div></div>      </div>
    </div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/index.html">What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html">About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/nanlei/freemarker/tree/manual-zh-2.3-gae/src/manual">Chinese Manual on Github</a></li><li><a href="https://github.com/freemarker/freemarker">FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker">Follow us on Twitter</a></li><li><a href="https://sourceforge.net/p/freemarker/bugs/new/">Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker">Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html">Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"><p><span class="generated-for-product">Generated for: Freemarker 2.3.23</span><span class="last-updated"> Last generated:
<time itemprop="dateModified" datetime="2015-09-18T14:38:51Z" title="Friday, September 18, 2015 2:38:51 PM GMT">2015-09-18 14:38:51 GMT</time></span></p> <p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2015
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://freemarker.org">The FreeMarker Project</a>. All rights reserved. </p>
</div></div></div></body>
</html>
